#
#        Python GUI - Application class - Generic
#

import os, sys, traceback
from Properties import Properties, overridable_property
from MessageHandlers import MessageHandler
from Exceptions import Cancel, Quit, UnimplementedMethod, UsageError
from StdMenus import basic_menus
from GMenus import MenuState
from Files import FileRef
from JHacks import * ##*change*

_application = None

class Application(Properties, MessageHandler):
    """The user should create exactly one Application object,
    or subclass thereof. It implements the main event loop
    and other application-wide behaviour."""
    
    _windows = None                # List of all existing Windows
    _documents = None            # List of all existing Documents
    _menus = []                        # Menus to appear in all Windows
    _clipboard = None

    def __init__(self):
        global _application
        if _application is not None:
            raise UsageError("More than one Application instance created")
        self._windows = []
        self._documents = []
        self._update_list = []
        self._idle_tasks = []
        _application = self
        self.menus = self.std_menus
        self._quit_flag = False
    
    def destroy(self):
        global _application
        _application = None

    #
    #        Constants
    #

    def get_std_menus(self):
        """Returns a list of Menus containing the standard
        framework-defined menu commands in their standard 
        positions."""
        return basic_menus()
    
    std_menus = property(get_std_menus)

    #
    #        Properties
    #

    def get_windows(self):
        return self._windows
    
    windows = overridable_property('windows', "A list of all existing Windows.")

    def get_documents(self):
        return self._documents
    
    documents = overridable_property('documents', "A list of all existing documents.")

    def get_menus(self):
        return self._menus

    def set_menus(self, menus):
        #if not isinstance(self, MenuList):
        #    menus = MenuList(menus)
        self._menus = menus
    
    menus = overridable_property('menus', """A list of Menus that are to be available from
        all Windows.""")

    #
    #        Event loop
    #

    def run(self):
        """The main event loop. Runs until a Quit exception
        is raised or _quit_flag is set."""
        self._open_args()
        while not self._quit_flag:
            try:
                self.event_loop()
            except (KeyboardInterrupt, Quit), e:
                return
            except SystemExit:
                raise
            except:
                self.report_exception()
    
    def event_loop(self):
        """Loop reading and handling events until _quit_flag is set
        or an exception other than Cancel is raised."""
        while not self._quit_flag:
            try:
                self.handle_events()
            except Cancel:
                pass
    
    def event_loop_until(self, exit):
        """Loop reading and handling events until exit() returns
        true, _quit_flag is set or an exception other than Cancel
        is raised."""
        while not exit() and not self._quit_flag:
            try:
                self.handle_next_event()
            except Cancel:
                pass

    def handle_events(self):
        """Handle events until an exception occurs. Waits for at least one event;
        may handle more, at the discretion of the implementation."""
        self.handle_next_event()
    
    def handle_next_event(self):
        """Wait for the next event to arrive and handle it. Transparently handles 
        any internal events such as window updates, etc., and executes any idle tasks 
        that become due while waiting for an event."""
        raise UnimplementedMethod(self, "handle_next_event")
    
    #
    #        Menu commands
    #

    def setup_menus(self, m):
        m.new_cmd.enabled = 1
        m.open_cmd.enabled = 1
        m.quit_cmd.enabled = 1

    def new_cmd(self):
        "Handle the New menu command."
        doc = self.make_new_document()
        doc.new_contents()
        self.make_window(doc)

    def open_cmd(self):
        "Handle the Open... menu command."
        from FileDialogs import request_old_file
        fileref = request_old_file()
        if fileref:
            self.open_fileref(fileref)

    def quit_cmd(self):
        """Handle the Quit menu command."""
        while self._documents:
            self._documents[0].close_cmd()
        while self._windows:
            self._windows[-1].destroy()
        self._quit_flag = True
        self._quit()

    def _quit(self):
        #  Implementations can override this to use some other means
        #  of stimulating the main event loop to exit.
        raise Quit
    
    #
    #   Opening files
    #
    
    def _open_args(self):
        for arg in sys.argv[1:]:
            if os.path.exists(arg):
                self.open_path(arg)
    
    def open_path(self, path):
        self.open_fileref(FileRef(path = path))
    
    def open_fileref(self, fileref):
            doc = self.make_file_document(fileref)
            if doc:
                doc.set_file(fileref)
                doc.read()
                self.make_window(doc)

    #
    #   Message dispatching
    #
    
    def dispatch(self, message, *args):
        target_window = self._find_target_window()
        if target_window:
            target_window.dispatch(message, *args)
        else:
            self.handle(message, *args)

    def _find_target_window(self):
        """Return the window to which messages should be
        dispatched, or None."""
        raise NotImplementedError
    
    #
    #        Abstract
    #

    def make_new_document(self):
        """Should create a new Document object of the appropriate 
        class in response to a New command."""
        raise UnimplementedMethod(self, 'make_new_document')

    def make_file_document(self, fileref):
        """Should create a new Document object of the appropriate 
        class for the given FileRef."""
        raise UnimplementedMethod(self, 'make_file_document')

    def make_window(self, document):
        """Should create a Window set up appropriately for viewing
        the given Document."""
        raise UnimplementedMethod(self, 'make_window')

    #
    #        Clipboard
    #

    def query_clipboard(self):
        "Tests whether the clipboard contains any data."
        return not not self._clipboard
    
    def get_clipboard(self):
        return self._clipboard

    def set_clipboard(self, x):
        self._clipboard = x
    
    #
    #   Window list management
    #
    
    def _add_window(self, window):
        if window not in self._windows:
            self._windows.append(window)
    
    def _remove_window(self, window):
        if window in self._windows:
            self._windows.remove(window)

    #
    #   Document list management
    #
    
    def _add_document(self, doc):
        if doc not in self._documents:
            self._documents.append(doc)
    
    def _remove_document(self, doc):
        if doc in self._documents:
            self._documents.remove(doc)
    
    #
    #   Exception reporting
    #

    def report_exception(self):
        """Display an alert box describing the most recent exception, and
        giving the options Continue, Traceback or Abort. Traceback displays
        a traceback and continues; Abort re-raises the exception so that
        the current run() call is terminated."""
        try:
            exc_type, exc_val, exc_tb = sys.exc_info()
            exc_desc = "%s: %s" % (exc_type.__name__, exc_val)
            from AlertFunctions import alert3
            message = "Sorry, %s encountered a problem and was unable to" \
                " complete the operation." % application_name
            result = alert3('stop', "%s\n\n%s" % (message, exc_desc),
                "Continue", "Abort", "Traceback",
                default = 1, cancel = None, width = 450, lines = 5)
            if result == 1:
                return
            elif result == -1:
                self.display_traceback(exc_desc, exc_tb)
                return
        except:
            print >>sys.stderr, "---------- Exception while reporting exception ----------"
            traceback.print_exc()
            print >>sys.stderr, "------------------ Original exception -------------------"
        #  Get here if we want to bail out of the application
        raise exc_type, exc_val, exc_tb
    
    def display_traceback(self, exc_desc, exc_tb):
        """Display an exception description and traceback. Currently the
        info is written to standard error; should be replaced sometime with
        a window."""
        import traceback
        sys.stderr.write("\nTraceback (most recent call last):\n")
        traceback.print_tb(exc_tb)
        sys.stderr.write("%s\n\n" % exc_desc)

    #
    #   Other
    #
    
    def zero_windows_allowed(self):
        """Platforms should implement this to return false if there
        must be at least one window open at all times. Returning false 
        here forces the Quit command to be used instead of Close when 
        there is only one window open."""
        # TODO: Move this somewhere more global.
        raise UnimplementedMethod(self, 'zero_windows_allowed')
    
    def _perform_menu_setup(self, menus = None):
        """Given a list of Menu objects, perform menu setup processing
        and update associated platform menus ready for popping up or
        pulling down."""
        if not menus:
            menus = self._effective_menus()
        menu_state = MenuState(menus)
        menu_state.reset()
        self.dispatch('_setup_menus', menu_state)
        for menu in menus:
            menu._update_platform_menu()
    
    def _effective_menus(self):
        """Return a list of the currently active menus, including both
        application-wide and window-specific menus, in an appropriate order
        according to platform conventions."""
        menus = self._menus
        window = self._find_target_window()
        #print "GApplication._effective_menus: window =", window ###
        if window:
            menus = menus + window._menus
        regular_menus = []
        special_menus = []
        for menu in menus:
            if menu.special:
                special_menus.insert(0, menu)
            else:
                regular_menus.append(menu)
        return regular_menus + special_menus

#------------------------------------------------------------------------------

_main_file_name = os.path.basename(sys.argv[0])
application_name = os.path.splitext(_main_file_name)[0]

#------------------------------------------------------------------------------

def application():
    """Returns the global Application object. Creates a default one if needed."""
    global _application
    if not _application:
        from Applications import Application
        _application = Application()
    return _application

def run():
    """Runs the application, retaining control until the application is quit."""
    application().run()

#------------------------------------------------------------------------------
#
#        $private
#
#------------------------------------------------------------------------------

